REFERENCE - EXTENDA.INC


CLpublic <FUNC1, FUNC2, ...>

Declares one or more functions public.  All functions to be
called from within a Clipper application must be declared public
in this way.  Function names must be upper case.


CLfunc ftype NAME <ptype p1, ptype p2, ...>

Declare a function.  NAME must be upper case.  The function type
determines how the specified value will be returned to Clipper
in the subsequent call to CLret.  Allowable function types
(ftype) are char, int, long, double, log, date, and void.  The
void type is for functions that return no value at all.
Allowable parameter types (ptype) are char, int, long, double,
log, and date.


CLcode

This macro must be called before the body of the function.  At
runtime, PCOUNT is set to the number of incoming parameters.
Missing parameters and parameters of the wrong data type are set
to zero.


CLret r

Type checking is enforced according to the return type specified
in the function declaration (CLfunc).  Allowable return values
(r) include any variable of the correct type, one or two 16-bit
registers depending on the size of the declared function type,
or nothing if the function has been declared void.


PCOUNT

Set by CLcode to the number of incoming parameters.  The value
stored in PCOUNT can be accessed at any point in the function.


TESTNUL variable

Sets the zero flag if variable is zero (NUL).  This macro can be
used to test any size variable, but MUST be called to test
pointers.


CODESEG segname

The default code segment is filename_TEXT where filename
represents the base name of the source file.  If this macro is
used to override the default, the code segment will be declared
as segname_TEXT instead.  This macro must appear before any
code-generating macros that would cause the default code segment
to be declared (i.e. CLfunc or WORKFUNCS).


DATASEG segname

This macro works much the same as CODESEG except that the DATA
segment is being declared.  The default data segment is _DATA.
Unlike CODESEG, however, DATASEG is not called automatically.
It is not necessary to call this macro unless there is static
data to be declared, in which case DATASEG must be called before
CLstatic.  The segname parameter is optional.


CLstatic <stype v1 i1, stype v2 i2, ...>

Declares static data where v is a variable and i is an initial
value to be placed in v.  Allowable static types (stype) are
byte, len, int, log, long, double, cptr, and string.  Several of
these types will be better understood with further explanation.

len is used to determine the size of the data block between the
current address and i, where i is a previously defined label.
For example:

    CLstatic <byte msg1 "This is a test...">
    CLstatic <len msglen1 msg1>
    CLstatic <byte msg2 "this is ONLY a test.">
    CLstatic <len msglen2 msg2, len msglen3 msg1>

This defines the following values:

    msglen1 = size of msg1
    msglen2 = size of msg2
    msglen3 = msglen1 + msglen2.

The cptr type will cause the additional symbols v_OFF and v_SEG
to be defined.  These symbols facilitate access to just the
segment or just the offset portion of a pointer.  Static
pointers can be initialized (at assembly time) to point to
static data.

The string type is much the same as byte except that a null byte
is added at the end of the string.


CLlocal <ltype l1, ltype l2, ...>

Declares auto (stack based) data.  This macro can only appear
between CLfunc and CLcode.  Allowable local types (ltype) are
char, int, long, double, log, and date.


CLextern <xtype x1, xtype x2, ...>

Declares external code and data.  Allowable external types
(xtype) are byte, int, log, long, double, cptr, and far.  Far is
used to declare external functions.  Cptr is used to access
external pointers in the form segment:offset.


CLlabel <ltype l1, ltype l2, ...>

Label a memory address using the assembler LABEL pseudo op.
Allowable label types (ltype) are byte, int, log, long, double,
cptr, and string.  The cptr type will cause the additional
symbols l_OFF and l_SEG to be defined.  These symbols facilitate
access to just the segment or just the offset portion of a
pointer.

Cglobal <v1, v2, ...>

Use this macro to make static data available to other modules.
Data declared global cannot be accessed directly by a Clipper
application, but other modules written in C or Assembly language
can share data this way.

Ccall cfunc <param1, param2, ...>

Call a C function.  This macro will handle all parameters and
stack manipulation to interface with the C language.  Param can
be any 16 bit register, a defined variable, or a constant
(immediate) value.  For example, if cfunc has been declared
external with CLextern:

Ccall cfunc <str, AX, i, 5>


WORKFUNCS

Begin local assembler routines.  This macro handles the segment
delarations only.  Within the WORKFUNCS block standard Assembly
language practice should be observed.  Procedures must be
declared explicitely and ended with the ENDP directive.


ENDWORK

End local assembler routines.  This macro must be called to
terminate the WORKFUNCS block.  If WORKFUNCS is followed by
CLfunc, ENDWORK will be called automatically.  However, if
WORKFUNCS is at the end of the file, ENDWORK must be called
explicitely.


SES reg16

The compliment of LES..stores ES and a named register to a DWORD
memory operand.  For example:

SES    DI, pointer_variable

SDS reg16

The compliment of LDS..stores DS and a named register to a DWORD
memory operand.  For example:

SDS    SI, pointer_variable


DOSREQ number

Calls DOS interrupt 21H with the request specified by number.
All necessary setup (other than loading the AH register) must be
performed before issuing this call.


$define symbol value

Makes assembler equate look like a C #define and may be used
instead of the assembler statement "symbol EQU value".


OFFPART p

The first word of a DWORD memory operand (segment:offset)


SEGPART p

The second word of a DWORD memory operand (segment:offset)


LSW n

The first word of a DWORD memory operand (32 bit number)


MSW n

The second word of a DWORD memory operand (32 bit number)


Special Note

The END directive that tells MASM when to stop is NOT generated
by any of the macros and must be entered explicitely.



REFERENCE - EXTEND SYSTEM ASSEMBLY LANGUAGE FUNCTIONS
-----------------------------------------------------

__PARC

Syntax Usage:

mov             x,<word>
push    ax
call    __PARC
add             p,2

Arguments:

<word> is the placement order in the parameter list.

Description:

This routine places the address of a Clipper character string in
DX:AX where:

DX = segment
AX = offset



__PARDS

Syntax Usage:

mov             x,<word>
push    ax
call    __PARDS
add             p,2

Arguments:

<word> is the placement order in the parameter list.

Description:

This routine places the address of a Clipper date stored as a
string in the form YYYYMMDD in DX:AX where:

DX = segment
AX = offset


__PARINFO

Syntax Usage:

mov             x,<word>
push    ax
call    __PARINFO
add             sp,2

Argument:

<word> is the placement order in the parameter list.

Description:

If the <word> argument is zero, __PARINFO places the number of
parameters passed in AX.  If the <word> argument is greater than
zero, _PARINFO places the type of the specified parameter in AX
using the following values:

Type                    Value placed in AX
----------------------------------
undefined               0
character               1
numeric                 2
logical                 4
date                    8
by reference    32
memo                    65

Note that only the SP, BP, DS, SS, CS and IP registers are
preserved.


__PARL

Syntax Usage:

mov     ax,<order>
push    ax
call    __PARL
add             sp,2

; Pass a parameter from an array.
mov     ax,<order>
mov     bx,<index>
push    bx
push    ax
call    __PARL
add             sp,4

Arguments:

Type: word <ORDER> is the placement order in the parameter list.

Type: word <INDEX> is the index of the array element to be
accessed.

Description:

This routine places the word of a Clipper logical value in AX
where 1 is true (.T.) and 0 is false (.F.).


__PARND

Syntax Usage:

mov     ax,<order>
push    ax
call    __PARND
add             sp,2

; Access a numeric double from a passed array.
mov     ax,<ORDER>
mov     bx,<INDEX>
push    bx
push    ax
call    __PARND
add             sp,4

Arguments:

Type: word <order> is the placement order in a parameter list.
Type: word <index> is the index of array element to be accessed.

Description:

This routine places the address of double passed from a Clipper
numeric in DX:AX where:

DX = segment
AX = offset

To get the value in AX:BX:CX:DX, you would:

mov             ax,<order>
push    ax
call    __PARND
add     sp,2
mov     es,dx
mov     si,ax
mov     ax,es:[si]
mov     bx,es:[si + 2]
mov     cx,es:[si + 4]
mov     dx,es:[si + 6]


__PARNI

Syntax Usage:

mov     ax,<order>
push    ax
call    __PARNI
add             sp,2

; Access a numeric integer from a passed array.
mov             ax,<order>
mov     bx,<index>
push    bx
push    ax
call    __PARNI
add             sp,4

Arguments:

Type: word <order> is the placement order in a parameter list.
Type: word <index> is the index of array element to be accessed.

Description:

This routine receives a Clipper integer number and places the
value in AX.


__PARNL

Syntax Usage:

mov             ax,<ORDER>
push    ax
call    __PARNL
add             sp,2

; Access a numeric long from a passed array.
mov     ax,<order>
mov     bx,<index>
push    bx
push    ax
call    __PARNL
add             sp,4

Argument:

Type: word <ORDER> is the placement order in the parameter list.
Type: word <INDEX> is the array element to access.

Description:

This routine receives a Clipper number as a long and places the
value in DX:AX.


__RET

Syntax Usage:

call __RET

Description:

For "DO" routines that do not return values.



__RETC

Syntax Usage:

mov     <register1>,<expN1>
mov     <register2>,<expN2>
push    <register1>
push    <register2>
call    __RETC
add             sp,4

Arguments:

<expN1> is the segment address of string.

<expN2> is the offset address of string.

Description:

__RETC passes back to Clipper a character string pointed to by
<register1> and <register2>.



__RETDS

Syntax Usage:

mov             <register1>,<expN1>
mov             <register2>,<expN2>
push    <register1>
push    <register2>
call    __RETDS
add             sp,4

Argument:

<expN1> is the segment address of date string.

<expN2> is the offset address of date string.

Description:

__RETDS passes back to a Clipper date a string in the form
YYYYMMDD.



__RETL

Syntax Usage:

mov             <register1>,<expN>
push    <register1>
call    __RETNL
add             sp,2

Argument:

<expN> is the value to return to a Clipper logical value where 0
is false (.F.) and 1 is true (.T.).

Description:

Passes back to Clipper a word value as a logical value.



__RETND

Syntax Usage:

mov     <register1>,<expN1>
mov             <register2>,< ?    >
mov             <register3>,< ?    >
mov             <register4>,< ?    >
push    <register1>
push    <register2>
push    <register3>
push    <register4>
call    __RETND
add             sp,8

Arguments:

<expN1> is the value to return to Clipper.

Description:

__RETND passes back to a Clipper a double precision number to
numeric.



__RETNI

Syntax Usage:

mov             <register1>,<expN1>
push    <register1>
call    __RETNI
add             sp,2

Argument:

<expN1> is the value to be return as an int.

Description:

__RETNI passes back to Clipper a number stored in
<register1> as a numeric.



__RETNL

Syntax Usage:

mov     <register1>,<expN1>
mov             <register2>,< ?   >
push    <register1>
push    <register2>
call    __RETNL
add             sp,4

Argument:

<expN1> is the long value to return to Clipper.

Description:

__RETNL passes back to Clipper a long integer stored in the
register pair <register1>:<register2> to a numeric.

.